﻿Public Interface iLibraryPlugin
  ''' <summary>
  ''' Raise this when your worker thread has completed and data is ready to be retrieved by the main thread.
  ''' </summary>
  Event NextMenuAsyncCompleted()

  ''' <summary>
  ''' If you need a setting from the application (something in settings.ini) you can raise this event at any
  ''' time as long as this event is raised on the main thread and is not raised in the constructor.  Do NOT
  ''' raise this event on a background thread or you may cause an exception.  There are no listeners wired up
  ''' yet when the constructor is called, so raising it there will cause no response.
  ''' </summary>
  ''' <param name="section">The INI file 'section' (the part in the square brackets) that you want to get the
  ''' setting from.</param>
  ''' <param name="key">The INI file 'key' in the section of the setting you want to get.</param>
  ''' <param name="value">This value will be overwritten by the event handler and will contain the requested
  ''' setting.  In the INI file, everything is stored as a string.  Non-string values are normalized as
  ''' integers.  Therefore, a BOOL type is 1 or 0, not TRUE or FALSE.  It's safe to test the literal string
  ''' value "0" and "1" to determine the boolean value.  A boolean will never be a different integer.  Be
  ''' aware of the bounds of non-string values.  Values of boolean, integer, and long are all valid.</param>
  ''' <param name="keyFound">This value is overwritten by the event handler and tells you whether or
  ''' not the requested key was valid.  This is FALSE if the section and/or key is not found.</param>
  Event GetApplicationSetting(ByVal section As String, ByVal key As String, ByRef value As String, ByRef keyFound As Boolean)

  ''' <summary>
  ''' This method is called once after instantiation and then again any time the user changes the language.
  ''' The recommended way to handle languages is to place your language file in the same Languages subfolders
  ''' the main language files are located, and to name them plugin.ini.  For example, for English and the
  ''' plugin Shoutcast, the file should be ...\Avian Play\Languages\English\shoutcast.ini.  The language
  ''' strings should be formatted as an INI.  To avoid string collisions, all strings used in your plugin should
  ''' also be prefixed by the plugin name.  For example, shoutcast_search might be the string that corresponds
  ''' to item to search shoutcast streams.  You are given all strings loaded for the current language,
  ''' including strings used by the main application, so feel free to use those in your plugin.  Since it
  ''' is entirely possible a particular language will not have a translation for your plugin, you should have
  ''' default strings compiled into your plugin to use in this scenario, if your strings are not found.
  ''' </summary>
  ''' <param name="lang">This is the language collection for the current user-selected language.</param>
  Sub SetLanguageStrings(ByVal lang As Language.LanguageReader)

  ''' <summary>
  ''' This method is called once after instantiation.  The values supplied indicate the library colors
  ''' specified in the skin definition.
  ''' </summary>
  ''' <param name="col">The colors in the skin definition</param>
  Sub SetColors(ByVal col As Colors)

  ''' <summary>
  ''' Go to the next menu.  The user has clicked on the item with the "key" string and is expecting another
  ''' menu.  You should return as quickly as possible or else do all your processing in another thread.  If
  ''' you return TRUE, processing was completed in its entirety in the NextMenu call.  If you return FALSE,
  ''' then processing is continuing in a background thread, and the app should asynchronously wait for you
  ''' to notify when processing is done.  Raise NextMenuAsyncCompleted when the Items() property is ready
  ''' to be queried.  It is okay to raise this on a worker thread, as the application will correctly
  ''' continue processing on the main thread, no matter where that event is raised.  This method MUST be
  ''' called once after initialization before the Items() property will return valid information.  If your
  ''' design does not require NextMenu() to be called, you must account for the fact it is called once
  ''' immediately after initialization.  The first call will pass an empty string to the plugin.
  ''' Subsequent calls will pass in the selected/clicked iLibraryItem.Key().
  ''' </summary>
  ''' <param name="key">The key of the item the user clicked on.</param>
  ''' <remarks>Don't forget to raise NextMenuAsyncCompleted after your processing is completed, if you
  ''' return FALSE, as the app will treat this as an asynchronous call.</remarks>
  Function NextMenu(ByVal key As String) As Boolean

  ''' <summary>
  ''' When this method is called, you are expected to terminate the asyncronous 'NextMenu' thread as quickly
  ''' as possible.  After this is called, if NextMenuAsyncCompleted is raised, it will be ignored.  Make
  ''' sure your internal breadcrumbs are updated to be in a state as if you never progressed to the next
  ''' menu, as PreviousMenu will not be called if this is called.
  ''' </summary>
  Sub CancelAsync()

  ''' <summary>
  ''' The user pressed "back" in the UI.  If you can go to a previous menu, return TRUE.  If you are at
  ''' the top menu already and need to return to the Avian Play built-in library (exit this plugin) then
  ''' return FALSE.  This is NOT an asynchronous operation, since the previous menu should be cached
  ''' somewhere.  Please note that if you need to clean up any resources, you must do it here as there
  ''' is no disposal called before unloading the plugin.  If you implement iDisposable, it is safe to
  ''' call Dispose() here as after the final PreviousMenu call, Avian Play will immediately set all
  ''' internal references to NULL.
  ''' </summary>
  Function PreviousMenu() As Boolean

  ''' <summary>
  ''' THIS FEATURE IS NOT AVAILABLE YET :: This is an optional function that provides a string that can be used to refresh the current list
  ''' in the future.  This is used for the automatic refresh feature of the "Now Playing" lists.  When
  ''' the user opens Avian Play, if the Now Playlist list contained content from this plugin, the string
  ''' provided here can be used to refresh the list.  The string may contain whatever you need to refresh
  ''' the data.  An example would be the complete URL used to request this data, if some sort of
  ''' internet radio directory was used.  Or perhaps some XML serialized settings.  It's up to you, but
  ''' please try to keep it small!  Return an empty string (String.Empty or "") if this feature is
  ''' not supported or a refresh string is unavailable (for example, the current Items() list contains
  ''' no AVPLPlaylistEntries).
  ''' </summary>
  Function GetRefreshListString() As String

  ''' <summary>
  ''' THIS FEATURE IS NOT AVAILABLE YET :: Using the supplied RefreshString (obtained from a call to GetRefreshListString previously), this
  ''' function will supply an iLibraryItem array (just like Items does) with a current list of items,
  ''' to make sure that the Now Playing list is up-to-date if it may change over time.  Return NULL
  ''' if the list is unable to be refreshed for some reason (any error) or if this feature is not
  ''' supported.  This operates completely outside of the rest of the properties and functions (like
  ''' Items()) and should not affect the state of menu traversal or items lists.  Only list entries
  ''' with a valid AVPLPlaylistEntry are supported since this is refreshing a Now Playing list and
  ''' not individual menus.  This call is synchronous, but will be called from a different thread
  ''' than the UI thread, so although it should be as fast as possible, it does not need to be real
  ''' time.
  ''' </summary>
  Function RefreshListFromString(ByVal RefreshString As String) As iLibraryItem()

  ''' <summary>
  ''' This property contains the items to display in the library menu.  It should return NULL until
  ''' at least one NextMenu has been called.  It should return an empty array if the list is empty.
  ''' If the user clicked on the last item and you do not want any deeper menu progression (as in, the
  ''' button is not a submenu or a playable item) then you should return NULL.
  ''' </summary>
  ReadOnly Property Items() As iLibraryItem()

End Interface
